home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / games / nhak_src.zip / INSTALL.AMI < prev    next >
Text File  |  1993-03-16  |  17KB  |  340 lines
  1.  
  2.     Instructions for compiling and installing NetHack 3.0
  3.             on an AMIGA system
  4.     =====================================================
  5.             Last Revision: 27 May 1990
  6.  
  7. Overview
  8. --------
  9.     This file contains the procedure to follow when installing NetHack 3.0
  10.     on an Amiga computer system.  It also includes some procedures and hints
  11.     for individuals desiring to create a binary from the source.  This
  12.     document is divided into 4 sections.  Section I deals with installing
  13.     already existing binaries and data files to create a working NetHack
  14.     game disk (or directory, in the case of a hard drive).  Section II
  15.     describes, in general, how to produce working binaries from the source.
  16.     Section III and IV are compiler specific sections, with section III
  17.     designed for Lattice users, and section IV for Manx/Aztec users.
  18.  
  19. Requirements
  20. ------------
  21.     Amiga 500,1000,2000,2500  running WorkBench 1.3 and KickStart 1.2 or 1.3.
  22.     (As of this time, the Amiga 3000 running beta-release versions of
  23.     WorkBench 2.0 are not supported.  While the core of the game appears to
  24.     function, the custom font is not recognized by the operating system.
  25.     The NetHack team welcomes reports of specific problems and solutions on
  26.     this [or any other] subject.)
  27.     one meg of RAM and one floppy drive (painful, but functional)
  28. or    one meg of RAM and two floppy drives (much better)
  29. or    more than one meg of RAM and a hard disk with 2+ meg free (best)
  30.  
  31. Credits
  32. -------
  33.     Olaf Seibert first ported NetHack 2.3 and 3.0 to the Amiga.  Richard
  34.     Addison, Jochen Erwied, Mark Gooderum, Ken Lorber, Greg Olson, Mike
  35.     Passaretti, and Gregg Wonderly polished and extended the 3.0 port.
  36.  
  37. Section I - Installation Guide
  38. -------------------------------
  39.     This section assumes you have the following handy:
  40.  
  41.     * NetHack (executable code)
  42.     * Rumors file
  43.     * Oracle file
  44.     * All of the various help and informational files (help, opthelp, etc)
  45.     * Special level files (castle, tower1, tower2, tower3, endgame)
  46.     * Amiga with at least 1 meg memory (may be optimistic....)
  47.  
  48.     And optionally:
  49.  
  50.     * Icons if WorkBench interface is to be used.  These files include
  51.         + NetHack.info
  52.         + NewGame.info
  53.         + NetHackScore.info
  54.         + Guidebook.info
  55.         + default.icon
  56.     * Special NetHack font (files hack.font and 8).
  57.  
  58.     Installation Steps:
  59.  
  60.     1) If you have a hard disk, create a directory named NetHack.
  61.        Assign Nethack: to be the path to this directory.  If you have a
  62.        floppy, format a disk named NetHack.  (If you have a hard disk
  63.        but only one meg of memory, you will probably not have enough
  64.        memory: you may need to run from a floppy.)
  65.  
  66.     2) If you have a hard disk, assign HackExe: to the above directory.
  67.        If you have a floppy, format an additional disk named HackExe.
  68.  
  69.     3) Copy Nethack, NetHack.info, NewGame.info, and NetHackScore.info
  70.        to HackExe.  Create an empty file called NewGame (WorkBench
  71.        refuses to Duplicate a project icon without a file attached).
  72.  
  73.     4) Copy the remainder of the files to NetHack:.  If you are using
  74.        the optional font, create a Hack subdirectory on NetHack:, and
  75.        copy "8" into it.  Be sure that Guidebook and Guidebook.info are
  76.        in the same directory, and that the Default Tool field points to
  77.        the More program (found on your AmigaDos System disk in the
  78.        Utilities directory).  Depending on where you got your copy of
  79.        NetHack, the Guidebook file may be called Guidebook.mss.
  80.  
  81.     5) Configure NetHack.cnf as per your configuration.  Remember not
  82.        to set GRAPHICS if you are not using the optional font.  If you
  83.        have only one meg of ram, do not use a ram disk.
  84.  
  85.     That's all there is to it!  If you are using the CLI interface, make sure
  86.     that the stack is set fairly large (at LEAST 40000 bytes).  Move to the
  87.     NetHack: directory, and type NetHack <cmd line options>.  If you're
  88.     using the WorkBench interface, click on the NetHack directory/disk.
  89.     You should see 3 icons.  Select the "NewGame" option, and "Duplicate" from
  90.     the WorkBench pull down menu.  This icon now represents your personal
  91.     profile.  You can now rename this icon, and tailor it to your liking
  92.     as described below.  If you start a game from the WorkBench interface,
  93.     saving the game will automatically tie the personal file icon to the
  94.     saved game.  So the next time you select your icon, the game will be
  95.     restored.
  96.  
  97.     As mentioned above, the icon representing your personal profile can be
  98.     customized.  This is done via the the Info command available from
  99.     WorkBench.  You can adjust the following using the ToolTypes from the
  100.     WorkBench info command:
  101.  
  102.     * OPTIONS=<options> - Options as avaliable in the NetHack.cnf file.
  103.  
  104.     * HACKDIR=<directory> - Set NetHack working directory to be this
  105.       directory.
  106.  
  107.     * RAMDISK=<ram disk> - Set up ram disk option.
  108.  
  109.     * LEVELS=<levels> - Intermediate level saving device/directory.
  110.  
  111.     * PATH=<path> - To search for files such as rumors, help, etc.
  112.  
  113.     * CMDLINE=<args> - Arguments as passed on the CLI command line.
  114.       Note:  only the following flags are valid: n, X, D, and r.
  115.  
  116.     * SCORE <options> - Display the record of scores.  Options as
  117.       available on the CLI command line after a -s flag.
  118.  
  119.     Note that the NetHack.cnf file is read first, then the ToolTypes.  This
  120.     means that the options specified in the NetHack.cnf act as defaults
  121.     which can be overridden by an individual's personal icon's ToolTypes.
  122.     Thus the system oriented entries (HACKDIR, RAMDISK, LEVELS, and PATH)
  123.     should generally be set only in NetHack.cnf.  NetHack.cnf should have
  124.     default values for OPTIONS, which will generally be overridden by
  125.     ToolTypes entries.
  126.  
  127.     Also, there is one additional option that may be specified in the
  128.     NetHack.cnf file or on an OPTIONS line: flush.  When enabled, flush
  129.     discards all characters in the queue except the first, which limits
  130.     but does NOT completely eliminate the "accidents" which can occur if
  131.     you get ahead of the game when typing.  The default setting is noflush.
  132.  
  133. Section II - General Compilation Instructions
  134. ---------------------------------------------
  135.  
  136.     1)  Before doing any compilation, read the README files distributed
  137.     with the source.  These should familiarize you with the source tree
  138.     layout, and what files are shared with what computers.  Generally,
  139.     everything in the amiga directory is used exclusively by the Amiga.
  140.  
  141.     2)  Create the sub-directories, and name them as indicated in the source
  142.     README file.  If you have a hard drive, this is fairly trivial
  143.     (create a directory, and corresponding NetHack sub-directories).
  144.     If you have only floppies, you'll have to be a bit more clever.
  145.     The makefile (Makefile.ami) is set up to depend upon certain
  146.         assignments, providing the developer with a fairly flexible
  147.     environment.  The main directory with which a floppy user will have
  148.         problems is the src directory.  In order to fit all of the source on
  149.     to floppies, the src directory has been split into logical units.
  150.     For example, the makefile expects:
  151.  
  152.         Src1:  contains src [a-l]*.c
  153.         Src2:  contains src [m-po]*.c
  154.         Src3:  contains src [pr-z]*.c
  155.  
  156.     See makefile.ami for assignment assumptions.
  157.  
  158.     3)  Edit config.h to your liking and system configuration.  The following
  159.     are strong suggestions for certain #define values.
  160.  
  161.         + UNIX - DO NOT DEFINE
  162.         + MSDOS - DO NOT DEFINE HERE, IT WILL BE DONE LATER FOR YOU
  163.         + COMPRESS - DO NOT DEFINE
  164.         + ZEROCOMP - DEFINE
  165.         + CHDIR - RECOMMENDED
  166.         + HACKDIR - "NetHack:" MANDATORY
  167.         + BITFIELDS - DO NOT DEFINE IF YOU HAVE MANX3.6
  168.         + CLIPPING - DO NOT DEFINE
  169.  
  170.     4) Edit amiconf.h to your liking.  It is recommended you leave
  171.        everything as is with the following exceptions:
  172.  
  173.             + TEXTCOLOR - Will allow the use of colors for text objects in
  174.               the game.  For instance, red gems will be red.  Unfortunately,
  175.               at this time this is only configurable at compile time, when
  176.           it really should be configurable at run time.  Note also that
  177.           there is a slight bug when running textcolor, namely that when
  178.           you are polymorphed, the color you are is not correct because
  179.           the cursor overlays the default monster color.  You can see
  180.           yourself fine, but you do not represent the correct monster color.
  181.  
  182.         + HACKFONT - Enable if you want to use the special NetHack font,
  183.           disable otherwise.
  184.  
  185.             + AMIGA_WBENCH - Enable if you want the WorkBench interface to
  186.           be compiled into the code. This does NOT preclude you from
  187.               running from CLI.
  188.  
  189.     5) If you have significant spare ram, you may wish to make your
  190.        compiler resident (Lattice 5.05's lc, lc1, and lc2 need about
  191.        215K while Manx's cc and as need about 135K).
  192.  
  193.     6) At this point, you're almost ready to begin a compile.  Read VERY
  194.        CAREFULLY through the Makefile to familiarize yourself with which
  195.        assignments are assumed.  Otherwise, you're going to get something
  196.        like "Insert O_Src1: in any drive." requestors.  If you have the
  197.        uudecode program and need to uudecode the various *.uu files from
  198.        the Amiga: directory (font and icons), define the UUDEC symbol
  199.        at the appropriate place in the makefile.  The first thing
  200.        Makefile.ami does is build a program called 'makedefs', which
  201.        handles a variety of data file generation, and a program called 
  202.        'lev_comp' which compiles the special levels.  Makedefs will then be
  203.        run to create a few files, followed by an alphabetically sorted
  204.        compilation of the entire source tree.  This compilation process
  205.        will compile selected files from Amiga:, Others:, Src1:, Src2:,
  206.        and Src3: directories.  If all goes well, all of the  objects will
  207.        be linked together to form a binary.  With all of the options
  208.        enabled, the Manx 3.6 executable runs about 790K, and the Lattice
  209.        executable runs about 750K (without debug hunks, or about 1025K
  210.        with debug hunks - see below).  After building the main binary,
  211.        the makefile will build and install the auxiliary files including
  212.        help files, special levels, icons, and the font files.
  213.  
  214. SECTION III - Lattice Compilation Instructions
  215. ----------------------------------------------
  216.  
  217.     If you're a Lattice user, you should be pretty well set up at this point.
  218.     If you have some spare ram, you may wish to examine the Amiga:compact.lat
  219.     script.  This script will reduce your compile time by using Lattice's
  220.     lcompact utility to pre-scan the header files and place compacted copies
  221.     onto the Ram: disk.  Read through the comments in that script if you
  222.     wish to utilize it.
  223.  
  224.     Due to a problem with versions 5.04 and 5.05, you must make one change:
  225.     edit the file Others:lev_lex.c.  At (or near) line 1003 is the definition
  226.     for the function yyunput.  Delete the word "register" from this line.
  227.     Note that if you neglect to do this, you will get an Error 72 at line 319
  228.     of file lev_comp.l (this is the correct message - lev_lex.c is flex output).
  229.     Save the changed file.  Later compiler versions may or may not need this
  230.     fix.
  231.  
  232.     Type 'CD NetHack:' and then type "lmk -f Amiga:Makefile.ami".  If all
  233.     goes well, you'll have a working binary a couple of hours later (depending
  234.     on your hardware configuration).  A couple of notes and warnings from the
  235.     Lattice users on the team:
  236.  
  237.     * The primary Lattice compiler used on the Amiga port was version
  238.       5.05.  Previous versions of NetHack have been successfully compiled
  239.       with 5.04 and 5.04a.
  240.  
  241.     * The function monsndx, in file mondata.c, has a section of code
  242.       which Lattice 5.04 compiles incorrectly.  A hack has been written
  243.       around this so that Lattice will generate the correct code.  It is
  244.       recommended that you leave this in place, and not attempt to
  245.       "improve" it.  This fix "does the right thing" in version 5.05.
  246.  
  247.     * Included in the Lattice port is code for generating a SnapShot.tb
  248.       file upon catching various internal disasters.  That is why the
  249.       -d1 flag is in the makefile.  This adds about 270K to the disk
  250.       image, but it does not increase the run time memory requirements.
  251.       Floppy users will have to delete -d1 flag, or the binary won't
  252.       fit on a single disk.
  253.  
  254.     * The optimizer seems to work, but no extensive testing has been
  255.       done with it.  (Note: optimizing objnam.c takes several hours.)
  256.  
  257.     * There are a large number of warnings under Lattice, which are
  258.       harmless.
  259.  
  260. SECTION IV  - AZTEC/MANX Compilation Instructions
  261. -------------------------------------------------
  262.  
  263.     NetHack 3.0 compiles and runs fine under Aztec 3.6, but a little bit
  264.     of work is necessary.  The problem is that the Aztec pre-processor
  265.     is fairly stupid, and doesn't recognize the defined() pre-processor
  266.     function.  Unfortunately, this function is laced throughout the NetHack
  267.     code, hence removing it would be quite a chore, and end up rendering the
  268.     code much more unreadable.
  269.  
  270.     There are a couple solutions to this problem.  The first solution is to
  271.     run every source file through some c pre-processor which understands
  272.     defined() (the Decus cpp works fine).  The problem with this solution is
  273.     that the time it takes to compile/recompile is (at least) doubled.  My
  274.     configuration is a 33 meg hard drive and 2 1/2 megs of ram, and it still
  275.     takes over 4 hours to generate a binary from scratch!  Also note that
  276.     Makefile.ami was not built to support cpp, and so you'll have to modify
  277.     the makefile to add this step.
  278.  
  279.     But don't despair, have we got a deal for you!  The Apple NetHackers also
  280.     had a similar problem with defined, which led them to developing a
  281.     defined() hack (located in config.h).  This hack basically adds
  282.     the defined() functionality to the Aztec pre-processor, with the exception
  283.     of performing this operation on strings.  Fortunately, using defined() on
  284.     strings is done very rarely, and they are handled on an individual basis.
  285.     (The only one I can think of right now is WIZARD/WIZARD_NAME).  What's the
  286.     catch, you ask?  Well, there is one. The problem is as follows.
  287.  
  288.     The Aztec compiler doesn't know how to handle const, volatile, and signed
  289.     data types.  Normally, this can be fixed by sticking a #define const
  290.     before const is used, thereby rendering it disabled.  Unfortunately, the
  291.     Aztec pre-processor, in its infinite wisdom, WILL NOT LET YOU REDEFINE
  292.     these strings.
  293.  
  294.     The solution to this is not quite as elegant as the solution to the
  295.     defined() problem above.  It requires a one time modification to the
  296.     Aztec cc binary.  (DO THIS TO A BACKUP COPY OF CC!!)  Find a disk zapper,
  297.     NewZap works fine.  Then do a search for the string 'const'.  Change
  298.     the const, signed and volatile strings to __nst, __gned and __latile.
  299.     (It's really not as bad as it sounds....)
  300.  
  301.     A couple of warnings regarding the 3.6 compiler/NetHack:
  302.  
  303.     * The 3.6 Manx bitfield handling is buggy at best.  Though I can't
  304.       specifically cite a flaw when NetHack is compiled with it, I
  305.       don't trust it.  I recommend you don't either.
  306.  
  307.     * If your signal.h (in your Manx include directory) has SIGINT
  308.       commented out, go ahead and uncomment it.
  309.  
  310.     * If you use the cpp method, pass -DAZTEC_C and -DMCH_AMIGA to
  311.           the cpp.  These are defined automatically by Aztec C, but are
  312.           ineffective if the source is run through a filter first.
  313.  
  314.     * There will be a few harmless warnings in the compile process.
  315.       These warnings will be in amidos.c, and pickup.c.  There may also
  316.       be a warning when defining lev_lex.c that LEV_LEX is redefined.  This
  317.       is OK.  Any other warnings should be investigated.
  318.  
  319.     * I haven't tried sdb on it, as I can't affort the disk space.  (You'll
  320.       have to save the intermediate cpp files if you cpp).  Unless you've
  321.           got a whopping amount of memory, I suspect it's going to be too large.
  322.  
  323.     * There are 2 versions of lev_lex.c that are being distributed; one
  324.       generated by (unix) lex, and one generated by gnu flex.  The gnu
  325.       flex lev_lex.c should work without modification.  If you use the
  326.           lex lev_lex.c, you will get 4 warnings regarding ptr/int conversions.
  327.           Change the masks from (int) to (long) to generate a clean binary.
  328.  
  329.     * Unfortunately, Manx 5.0 arrived too late to integrate into patch
  330.       level 7, but merging will occur in the next few weeks.  Contact us
  331.       (below) for progress/hints.  (Postscript for PL8: the situation is
  332.       very much improved, but there may be some problems remaining).
  333.  
  334.             - - - - - - - - - - - -
  335.  
  336. If you have problems or questions, email to nethack-bugs@linc.cis.upenn.edu,
  337. or directly to Greg Olson (golson@sundown.sun.com)  for Manx questions,
  338. to Ken Lorber (keni@dtix.dt.navy.mil) for Lattice questions, or to
  339. Richard Addison (addison@pollux.usc.edu) for either.  Have fun!!
  340.